<html xmlns="http://www.w3.org/1999/xhtml" id="program-structure">
<head>
  <title>Program Structure</title>
</head>

<body>

<h1>Program Structure</h1>

<h2><a name="canvas-tag"/>The canvas tag</h2>

<p>An LZX application has exactly one canvas.  The canvas is the
container for all views and elements of the application.</p>

<p>An LZX application file is an XML file whose document root is a
canvas element.  The canvas contains attributes and elements that
configure and define the application.  For example,</p>

<example class="code" title="Hello World">
&lt;canvas height="15"&gt;
  &lt;text&gt;Hello, World&lt;/text&gt;
&lt;/canvas&gt;
</example>

<p>is a simple LZX application. The canvas has a height and width
measured in pixels; if you do not specify values for these attributes
the default width  and height are "100%".</p>
<p>
In addition to the LZX code contained in the &lt;canvas&gt; block, Laszlo applications 
may use code contained in separate library files. These libraries can be either compiled
into the main program (using the <tagname>include</tagname> tag) or separately compiled and downloaded at 
run time (the <tagname>import</tagname> tag).  These are described below.
</p>

<h3>Files included at compile time</h3>
<p>An LZX application file may include other LZX files using the
<tagname link="true">include</tagname> element.  When you use the <tagname link="true">include</tagname> tag, the
libraries you reference will be compiled into the program.
</p>
<p>
For example,</p>

<example extract="false" title="Simple include">
&lt;canvas&gt;
  &lt;include href="hello-incl.lzx"/&gt;
&lt;/canvas&gt;
</example>

<example filename="hello-incl.lzx" executable="false" extract="false">
&lt;library&gt;
  &lt;text&gt;Hello World!&lt;/text&gt;
&lt;/library&gt;
</example>

<h3>Files imported at run time</h3>

<p>
A dynamic library is a portion of a program that can be loaded after the main application execution file has loaded. The goal for dynamic
 libraries is to reduce the initial download size of a Laszlo application. This is required because initial download size (including all 
requests that precede initial user interaction) is used to evaluate web applications. Reducing the initial download size has 
the additional benefits of reducing the time to first interaction (although there are other ways of doing this), and of reducing 
bandwidth costs in the case where an optional feature of the application is not used.
</p>
<p>
Imported libraries can contain classes, instances, datasets, and &lt;script&gt; blocks. But any media resources in them are moved to the main (calling) application.  For example, if this tag is included in the library file to be imported,</p>
<pre>
&lt;view resource="foo.png"/&gt;
</pre>
<p>
the image resource is baked into the canvas application itself as a Flash resource. This means that  the image is downloaded with the calling file, not the called file, as one might otherwise expect.</p>
<p>
Resources that are loaded over http, as for example,
</p>
<pre>
&lt;view resource="http:foo.png"/&gt; 
</pre>
<p>
are still compiled into  a runtime request. </p>


<h3>Summary comparison of &lt;include&gt; and &lt;import&gt;</h3>
<p>
&lt;include&gt; and &lt;import&gt; both break an application into source files: they let you distribute an application's sources among multiple source files.  They address developer workflow, code ownership, and source control issues.
</p>
<p>
However they are incorporated into an application, all library files share the same namespace.
</p>
<p>
&lt;import&gt; additional breaks an application into multiple delivery components: they let an application defer download of some components.  It addresses the initial download size of an application; nothing more.  It is intended for the scenario where all the source files are available when an application is created; it's synonymous with &lt;include&gt; except that the bits it creates are distributed across multiple files, instead of all placed in one file.  These bits can't be mixed and matched any more than the bits in a single-object-file application created with &lt;include&gt; can.
</p>
<p>
OpenLaszlo does not support separate compilation: the library files will only work with the specific application file that they were compiled against, and vice versa.  
</p>
<p>
The rest of this chapter explores these concepts in greater detail.
</p>

<fixme> update the section below if and when we make public the javascript API</fixme>
<!--
<h3>JavaScript API</h3>
<p>
<code>library.load() </code>loads a library that was imported by <code>&lt;import ... name="library" initstage="defer"/&gt;. </code>
If initstage != 'defer' or the library was already loaded, library does nothing.</p>
<p>
Due to the asynchronous nature of browser requests, it is possible that this call will have no immediate effect upon other properties, 
such as loaded, of the library object.
</p>
<p>
library.loaded is true if and only if the library has been loaded.
</p>
<p>
<code>LzLibrary.load("uri", object)</code> loads a library. The global values that the library defines are placed as attributes 
in object. If the function is called with only one parameter, the global values are placed in globals instead. 
</p>
-->



<h2><a name="include-tag"/>The <tagname>include</tagname> tag for compiled-in libraries</h2>

<p>The <tagname>include</tagname> tag implements the 
<a href="http://www.w3.org/TR/xinclude/">XInclude</a> standard for XML
inclusions.  The <tagname>include</tagname> tag can be used in three
ways:</p>
<ul>
<li>To include a <tagname link="true">library</tagname> file.</li>
<li>To include an element hierarchy.</li>
<li>To include text from a text file.</li>
</ul>

<p>The source code for a Laszlo application can be contained in a
single source file which specifies all aspects of the application.
Alternatively, the <tagname>include</tagname> and <tagname
link="true">library</tagname> tags can be used to separate the
source for an application into multiple files.</p>

<p>By dividing your application into a number of files, you can limit
the size of your source files to a maintainable size. You can even
break deep view hierarchies into multiple files, as is done in the <a
href="${demos}contacts">contacts</a> example, to improve
modularity, clarity and source code organization.</p>

<p>The value of the <attribute>href</attribute> attribute is the name
of a file whose content is included at the point of the
<tagname>include</tagname> element. This is the <i>target</i> of the
include.</p>

<h3>Including a Library</h3>

<p>When the target is a <i>library file</i> (an XML file whose root
element is <tagname link="true">library</tagname>), the contents of
the library file are included in the application.  Any views, scripts,
fonts, resource, audio, datasource, dataset, and class definitions in
the library file are included in the application.  A library file can
include other libraries, but a library is included in an application
only once, no matter how many include statements reference it.  For
example:</p>

<example title="Including a library file" class="program" id="include-1">
&lt;canvas height="100" width="400"&gt;
  &lt;include href="library.lzx"/&gt;
  &lt;mywindow/&gt;
&lt;/canvas&gt;
</example>

<example class="program" filename="library.lzx" executable="false">
&lt;library&gt;
  &lt;class name="mywindow" extends="window"
   title="MyTitle"&gt;
    &lt;button&gt;Click me!&lt;/button&gt;
  &lt;/class&gt;
&lt;/library&gt;
</example>


<h3>Including an instance</h3>
<p>When the target is an XML file that is not a library file, its root element is included at the point of the include element. 
 This can be used to break a view hierarchy into multiple files.  Unlike including a library file, a non-library file is inserted once each time it is included.</p>

<p>The following example shows a view with two buttons, both labeled
"Click me!":</p>

<example class="program" title="Including a node" id="include-3">
&lt;canvas height="100"&gt;
  &lt;window layout="axis: y"&gt;
    &lt;include href="inner.lzx"/&gt;
    &lt;include href="inner.lzx"/&gt;
  &lt;/window&gt;
&lt;/canvas&gt;
</example>

<example title="inner.lzx" filename="inner.lzx" executable="false">
&lt;button&gt;Click me!&lt;/button&gt;
</example>

<p>The <a href="${demos}contacts">contacts</a> example uses
includes in this way to break a large program into multiple files.</p>

<h3>Including Text</h3>

<p>If the type attribute has the value <code>text</code>, the included
file is included as characters, rather than XML.  This can be used to
include literal text from another file.</p>

<example title="Including text" class="program" id="include-5">
&lt;canvas height="100"&gt;
  &lt;window&gt;
    &lt;button&gt;
      &lt;include href="mytext.txt" type="text"/&gt;
    &lt;/button&gt;
  &lt;/window&gt;
&lt;/canvas&gt;
</example>

<example title="mytext.txt" class="program" filename="mytext.txt" executable="false">
Click me!
</example>
<h2><a name="library-tag"/>The <tagname>library</tagname> tag</h2>
<p>A library file is a file contained in a <tagname>library</tagname> tag.  A library file cannot be compiled to
an application, but an application can include library files through
use of the <tagname>include</tagname> tag.  Library files are
used to break an application's source into multiple files, or to share
code among multiple applications.</p>

<p>For example, instead of defining a view as in <code>&lt;canvas>&lt;window
title="mywindow"/>&lt;/canvas></code>, an application can include a
library that defines the view.  In this case, the application's canvas
source file would read <code>&lt;canvas>&lt;include
href="mylib.lzx"/>&lt;/canvas></code>, and <code>mylib.lzx</code> would contain the definition <code>&lt;library>&lt;window
title="mywindow"/>&lt;/library></code>.</p>

<p>A library file can contain any element that a canvas source file
can contain, except for the <tagname>splash</tagname>,
<tagname>connection</tagname>, and <tagname>debug</tagname> elements.
Including a library includes the elements &#x2014; code, views, and
definitions &#x2014; in the library.</p>

<p>An application only contains one copy of each library, no
matter how many includes for that library its source files contain.
For example, <code>&lt;canvas>&lt;include
href="mylib.lzx"/>&lt;include href="mylib.lzx"/>&lt;/canvas></code> is
equivalent to the previous example: only one window is defined.</p>
<h3>Library directories</h3>

<p>If a directory contains a file named <code>library.lzx</code>, you
can include that file by referencing the name of the directory. For
example, the <code>utils</code> components directory contains a file
named <code>library.lzx</code>.  Therefore, the following two
fragments have the same effect:</p>

<example title="Include library.lzx file" extract="false">
&lt;include href="utils/library.lzx"/&gt;
</example>

<example title="Include directory with library file" extract="false">
&lt;include href="utils"/&gt;
</example>

<p>Similarly, you can write <code>&lt;include
href="utils/states"/&gt;</code> to include the files that the
file <code>utils/states/library.lzx</code> includes, and
<code>&lt;include href="lz"/&gt;</code> to include the Laszlo
component set.</p>

<h4><a name="autoinclude">Auto-includes</a></h4>

<p>Some of the distributed components are automatically included, if the application references them.  If the application uses a tag that it has not defined, but that is defined in the <code>base</code>, <code>lz</code>, <code>charts</code> or <code>utils</code> directory, the file that contains this class is included.  The following pairs of programs are therefore equivalent:</p>

<example title="Use button with explicit include">
&lt;canvas height="50"&gt;
  &lt;include href="lz/button.lzx"/&gt;
  &lt;button&gt;Click me!&lt;/button&gt;
&lt;/canvas&gt;
</example>

<example title="Use button with implicit include">
&lt;canvas height="50"&gt;
  &lt;button&gt;Click me!&lt;/button&gt;
&lt;/canvas&gt;
</example>

<example title="Subclass button with explicit include">
&lt;canvas height="50"&gt;
  &lt;include href="lz/button.lzx"/&gt;
  &lt;class name="mybutton" extends="button" fgcolor="red"/&gt;
  &lt;mybutton&gt;Click me!&lt;/mybutton&gt;
&lt;/canvas&gt;
</example>

<example title="Subclass button with implicit include">
&lt;canvas height="50"&gt;
  &lt;class name="mybutton" extends="button" fgcolor="red"/&gt;
  &lt;mybutton&gt;Click me!&lt;/mybutton&gt;
&lt;/canvas&gt;
</example>

<p>A file is only included if the application references a class that it does not define in its own sources.  The following two programs define their own <tagname link="false">button</tagname> tag, and therefore do not implicitly include the file that defines the Laszlo <tagname>button</tagname> tag.</p>

<example title="Define button">
&lt;canvas height="50"&gt;
  &lt;class name="button"&gt;
    &lt;text&gt;Click me!&lt;/text&gt;
  &lt;/class&gt;
  &lt;button/&gt;
&lt;/canvas&gt;</example>

<example title="Define and subclass button">
&lt;canvas height="50"&gt;
  &lt;class name="button"&gt;
    &lt;text&gt;Click me!&lt;/text&gt;
  &lt;/class&gt;
  &lt;class name="mybutton" extends="button" fgcolor="red"/&gt;
  &lt;mybutton/&gt;
&lt;/canvas&gt;
</example>
<h4>More on base components</h4>
<p>An application can include the entire set of Base components by
including the line <code>&lt;include
href="base"/&gt;</code>.  An application can include individual Base
components by including just the files that define those components.
The Base components are included automatically if an application
refers to them but does not define or include them.  </p>

<h2>The <tagname>import</tagname> tag for runtime includes</h2>
<p>
The tag <tagname link="true">import</tagname>, is used to include dynamic libraries. 
</p>
<p>
The <tagname>import</tagname> tag must occur at the top level of an application 
(as the immediate child of the <tagname>canvas</tagname> or <tagname link="true">library</tagname> document root element of a file).
</p>
<p>
 The syntax of the import tag is as follows:
</p>
<pre>
 &lt;import href="mylib.lzx" prefix="ns" stage="late"/&gt;
</pre>
<p>
All attributes except href are optional. The "href" attribute of an import statement is the pathname of a library file. 
The pathname is resolved relative to the pathname of the file that contains the import statement.
</p>
<p>
The &lt;import&gt; tag has these attributes:
</p>
<table summary="Attributes for &lt;import&gt;">
  <tr><th>name</th><th>type</th><th>default</th><th>description</th></tr>
 
  <tr>
    <td><code>href</code></td>
    <td>URI</td>
    <td>required</td>
    <td> The URI of a file that defines the library. In the case where stage is compile (the default), this has the same meaning as it does 
in an &lt;include&gt; tag. If stage="deferred", the URI is resolved relative to the location of the location of the file that contains 
the &lt;import&gt; element,
 and a request for this URI is sent to the server to request a library file that is downloaded into the running application.
    </td>
  </tr>
   <tr>
    <td><code>stage</code></td>
    <td>  "late" | "defer"</td>
    <td>compile</td>
    <td> If stage is "normal", the contents of the library are linked into the application at compile time. If it is "defer", the statement 
defines an object whose name is the value of the name attribute, and that can be used to load the library during the execution of 
the application via the API specified in Dynamic Libraries.</td>
  </tr>
  <tr>
    <td><code>name</code></td>
    <td>JavaScript Identifier</td>
    <td>global</td>
    <td> If this is not empty, it is the name of an ECMAScript object whose properties are the global ECMAScript names 
(classes, functions, objects) that the library defines. If it is not empty and is the name of a namespace prefix that the 
including file defines with a xmlns or xmlns:prefix attribute, tag names such as myclass that the library defines 
are accessible outside the library as prefix myclass.</td>
  </tr>
 <tr>
    <td><code>prefix</code></td>
    <td>XML namespace prefix </td>
    <td>""</td>
    <td>
 If this is not empty, it must be an XML namespace prefix that is in scope on the &lt;import&gt; element. In this case, 
class definitions in the target library are bound to XML tags in the specified namespace.</td>
  </tr>
</table>
<p></p>
<p>
The stage attribute may have the value "late" or "defer". A "late" library is imported once the main application file 
has finished loading. A "defer" library is loaded programmatically via a JavaScript method on the object bound to the variable named
 by the value of its "name" attribute; in this example, "mylib".
</p>
<pre>
 &lt;import name="mylib" href="lib/foo.lzx" stage="defer" onload="doSomething()"/&gt;
</pre>
<p>
Other view attributes <code>onload, onerror, </code>and <code>ontimeout</code> are also supported:
</p>

<ul>
	<li>The code supplied to 'onload' will be executed once the library has loaded successfully.</li>
	<li>It is an error for a program to contain an XML reference to a class that is defined in a late or defer library. </li>

</ul>
<h3>Positioning of imported library views </h3>                                               
<p>
Say you had a view, call it "blueview" in a library to be imported.  If you merely used the <method>load</method>to import the code for "blueview", you would see the view show up at the bottom of the application, not at the place where the method was invoked. This is because the <method>load</method> method only tells <tagname>import</tagname> what to load, not where to load it.
To get the effect we want, we could define a class in a library
and instantiate it dynamically. (The following discussion assumes an understanding of delegates and timers, explained in <xref linkend="delegates"/>.)
</p>
<p>
 To do position code where we want it in the importing application, we would make a delegate that directly listens for the
<event>onload</event> event from the &lt;import&gt; and instantiates the class (or calls a method to do so).  Something like:</p>
<pre>
   &lt;method event="onload" reference="blueview"&gt;
      this.makeChild({name: 'blueview', ...});
   &lt;/method&gt;
</pre>
<p>
We could define an <method>onload</method> on &lt;import&gt; to call a method to set a global variable "loaded" to true. 
</p>
<p>
Then, at the place where we want blueview to appear, we could load the library and then set up a delegate and timer which calls a method to see if the variable
"loaded" is true, and if not reset the timer.  If it is true--that is, if the class has been loaded-- the view is created.
</p>


<h2>Debugging</h2>
<p>An LZX application can be debugged by requesting that the
application be compiled in debug mode by setting the canvas's
<attribute>debug</attribute> attribute to true:</p>

<example class="code" title="Compiling with the debugger">
&lt;canvas height="140" debug="true"&gt;
  &lt;!-- ... --&gt;
&lt;/canvas&gt;
</example>

<p>This has the same effect as pressing the Debug button in the
developer console.</p>

<p>See <xref linkend="debugging"/> 
for more information on using the
debugger.</p>

<note>It is also possible to invoke the debugger by loading the
application using the <code>?debug=true</code> query parameter.  See
<xref linkend="request-types.query-parameters"/> of <xref
linkend="request-types"/> for more information on using the
debugger.</note>

<h2>Resources, Fonts, and Datasources</h2>
<p>In addition to including classes and instances, a library file can use the <tagname link="true">font</tagname>,
<tagname link="true">resource</tagname>, and <tagname
link="true">datasource</tagname> tags to include fonts, media
resources, and XML datasources defined in external files as well.</p>

<p>Elements within an application, such as <tagname
link="true">script</tagname>, <tagname link="true">class</tagname>,
and extensions of <tagname link="true">view</tagname>, are evaluated
in the order that they appear in the source file.  In particular, code
in a <tagname link="true">script</tagname> element cannot refer to
<tagname link="true">view</tagname> elements that follow it.</p>

</body>
</html>
<!-- * X_LZ_COPYRIGHT_BEGIN ***************************************************
* Copyright 2001-2004 Laszlo Systems, Inc.  All Rights Reserved.              *
* Use is subject to license terms.                                            *
* X_LZ_COPYRIGHT_END ****************************************************** -->
